{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Circular flow in a district heating grid\n",
    "\n",
    "This example shows how to set up and solve the following network:\n",
    "\n",
    "<img src=\"pics/heat.png\">\n",
    "\n",
    "In this example, we will not only calculate the pressure and velocity distribution in the network, but also determine the temperature levels. The pump feeds fluid of a given temperature into the grid. Due to losses, the temperature will fall. The heat exchanger removes more heat from the network. On its way back to the pump, the temperature will fall further. \n",
    "\n",
    "The network is based on the topology of a district heating grid, where the fluid returns to the pump after the consumers (heat exchangers) have been supplied.\n",
    "\n",
    "To set up this network, at first, the pandapipes package has to be imported. Additionally, a net container is created and, at the same time, water as a fluid is chosen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapipes as pp\n",
    "\n",
    "# create empty net\n",
    "net = pp.create_empty_network(fluid =\"water\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the flow of the example network flows in a closed loop. We will need four junctions.\n",
    "The parameters `pn_bar` and `tfluid_k` that have to be set in the `create_junction`-function\n",
    "are\n",
    "only used as starting points for the network simulation. The fix pressure and fluid temperature is\n",
    "being determined by the circular pump component which will be created afterwards."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "j0 = pp.create_junction(net, pn_bar=5, tfluid_k=293.15, name=\"junction 0\")\n",
    "j1 = pp.create_junction(net, pn_bar=5, tfluid_k=293.15, name=\"junction 1\")\n",
    "j2 = pp.create_junction(net, pn_bar=5, tfluid_k=293.15, name=\"junction 2\")\n",
    "j3 = pp.create_junction(net, pn_bar=5, tfluid_k=293.15, name=\"junction 3\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, the pump will be created. The type of pump we choose needs a mass flow, a pressure level and a\n",
    "temperature as input. Note that the circular pump is a component, which internally consists of an\n",
    "external grid, connected to the junction specified via the from_junction-parameter and a sink,\n",
    "connected to the junction specified via the to_junction-parameter.\n",
    "\n",
    "However, the internal structure is not visible to the user, so that the circular pump component\n",
    "supplies a fluid flow with the specified properties."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.create_circ_pump_const_mass_flow(net, return_junction=j3, flow_junction=j0, p_flow_bar=5,\n",
    "                                    mdot_flow_kg_per_s=20, t_flow_k=273.15+35)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, the heat exchanger component is created.\n",
    "The most important parameter for this component is the heat flux `qext_w`. A positive value of\n",
    "`qext_w` means that heat is withdrawn from the network and supplied to a consumer.\n",
    "A negative value of `qext_w` corresponds to a heat source, i. e. thermal energy is being transfered\n",
    "from the heat exchanger into the network."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.create_heat_exchanger(net, from_junction=j1, to_junction=j2, diameter_m=200e-3, qext_w = 100000)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following commands defines the pipes between the components. Each pipe will consist of five\n",
    "internal sections in order to improve the spatial resolution for the temperature calculation.\n",
    "The parameter `text_k` specifies the ambient temperature on the outside of the pipe. It is used to\n",
    "calculate energy losses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.create_pipe_from_parameters(net, from_junction=j0, to_junction=j1, length_km=1,\n",
    "                               diameter_m=200e-3, k_mm=.1, u_w_per_m2k=10, sections = 5, text_k=283)\n",
    "pp.create_pipe_from_parameters(net, from_junction=j2, to_junction=j3, length_km=1,\n",
    "                               diameter_m=200e-3, k_mm=.1, u_w_per_m2k=10, sections = 5, text_k=283)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "We now run a pipe flow.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.pipeflow(net, mode='sequential')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, only the pressure and velocity distribution is calculated by the pipeflow function. If\n",
    "the `mode`-parameter is set to \"all\", the heat transfer calculation is started automatically\n",
    "after the hydraulics computation. Computed mass flows are used as an input for the temperature\n",
    "calculation. After the computation, you can check the results for junctions and pipes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "net.res_junction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that a constant heat flow is extracted via the heat exchanger between nodes 1 and 2. Heat\n",
    "losses due to the ambient temperature level are not taken into account. These are only included in\n",
    "the pipe components. This also means that - if the extracted heat flow is large enough - the\n",
    "temperature level behind the heat exchanger might be lower than the ambient temperature level. A\n",
    "way to avoid this behaviour would be to create a controller which defines a function for the\n",
    "extracted heat in dependence of the ambient temperature."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "net.res_pipe"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The command above shows the results for the pipe components. The temperatures of the adjacent\n",
    "junctions are displayed. Due to heat losses, the temperatures at the to-nodes is lower than the\n",
    "temperatures at the from-nodes. Note also that the junctions are not equal to the internal nodes,\n",
    "introduced by the pipe sections we defined. To display the temperatures at the internal nodes, we\n",
    "can retrieve the internal node values with the following commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandapipes.component_models import Pipe\n",
    "pipe_results = Pipe.get_internal_results(net, [0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The parameters of the get_internal_results function correspond to the net and the pipes we want to\n",
    "evaluate. In this case, only the results of pipe zero are retrieved. The returned value stored in\n",
    "pipe_results is a dictionary, containing fields for the pressure, the velocity and the temperature.\n",
    "The dictionary can either be used for own evaluations now or it can be used to plot the results over\n",
    "the pipe length:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Pipe.plot_pipe(net, 0, pipe_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the pressure level falls due to friction. As the fluid is incompressible, the\n",
    "velocity remains constant over the pipe length. Because the temperature level at the pipe entry is\n",
    "higher than the ambient temperature, the temperature level decreases."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
